home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d21 / dvglue.arc / -DVGLUE.DOC < prev    next >
Text File  |  1990-01-09  |  45KB  |  1,066 lines
  1.                         DV-GLUE v0.91
  2.                         -------------
  3.                (c) Copyright 1988  Ralf Brown
  4.                     All Rights Reserved.
  5. [See file -COPYRIT.NOT for full copying permissions/restrictions]
  6.  
  7. DV-GLUE is a collection of some 225 functions which give your programs access
  8. to the power of the DESQview[*] and TopView[**] environments.  You may use
  9. them freely provided you do not try to make money off of the programs you
  10. write using them.  Donations are neither required nor expected, but wouldn't
  11. be turned down.
  12.  
  13. DV-GLUE implements all but nine of the functions described in Quarterdeck's
  14. DV API library flyer, and several dozen additional functions.
  15.  
  16.  
  17. ---
  18. [*] DESQview (tm) is a trademark of Quarterdeck Office Systems
  19. [**] TopView (tm) is a trademark of International Business Machines, Inc.
  20.  
  21. -----------------------------------------------------------------------------
  22. To use this library in your own programs, add the line
  23.         #include "tvapi.h"
  24. to the start of each source file using functions from the library.  If you
  25. are using constants for building your own streams, also add the line
  26.         #include "tvstream.h"
  27. to the start of the module.  Then add TVAPI.LIB to the list of files to
  28. compile (if you are using TCC), or add TVAPI.LIB to the .PRJ file.
  29.  
  30. If you have been using version 0.7, see -HIST for details of the massive
  31. function renamings which have taken place.
  32. -----------------------------------------------------------------------------
  33. A number of the functions at the core of this package were originally written
  34. by John Navas.  The original versions of these can be found in the file
  35. TVGLUETC.ARC on the Dog Lab BBS (415) 594-9806.
  36.  
  37.  
  38.         Ralf Brown
  39.         July 10, 1988
  40.  
  41. Direct e-mail to:
  42.         ralf@cs.cmu.edu                      (Arpanet)  \
  43.         ralf%cs.cmu.edu@cmuccvma             (BITnet)    > preferred
  44.         ...!{harvard,ucbvax}!cs.cmu.edu!ralf (UUCP)     /
  45.         Ralf Brown 1:129/31                  (FIDOnet)
  46.         [No Compu$pend/$ource/GEnie accounts....]
  47. -----------------------------------------------------------------------------
  48.  
  49. Setup
  50. -----
  51.  
  52. Before you can call any of the functions in this library, you must first
  53. initialize the library by calling either TVinit() or DVinit().  TVinit()
  54. will allow you to use the functions which work under both TopView and
  55. DESQview, while DVinit() will also allow you to use those functions which are
  56. unique to DESQview.
  57.  
  58. At the end of the program, before exiting, you must call either TVexit() or
  59. DVexit().  If you called TVinit() at the beginning, call TVexit() at the end.
  60. If you called DVinit(), then call DVexit().
  61.  
  62. int TVinit(void)
  63.         initialize TopView interface and return TopView version as a hex
  64.         number: 0x010A == version 1.10
  65. void TVexit(void)
  66.         clean up TopView interface before terminating program
  67. int DVinit(void)
  68.         initialize DESQview interface and return DESQview version as a hex
  69.         number: 0x0201 == version 2.01
  70. void DVexit(void)
  71.         clean up DESQview interface before terminating program
  72.  
  73. Low-Level Primitives
  74. --------------------
  75.  
  76. Most of the functions described in later sections call on one or more of the
  77. functions in this section.
  78.  
  79. void TVwin_stream(OBJECT window,BYTE *stream)
  80.         send the specified stream to the window.  The only restriction on the
  81.         stream is that it may not contain window-stream opcode E6h (create
  82.         new window).
  83.  
  84. OBJECT TVwin_new(OBJECT window,int rows,int cols)
  85.         create a new window of the specified dimensions which becomes a child
  86.         of the given window, and return its handle.
  87.  
  88. void TVsendmsg(int message,int modifier,OBJECT object,PARMLIST parameters)
  89.  
  90.         
  91. void TVsendmsg0(int message,int modifier,OBJECT object)
  92.         send a parameterless, non-value-returning message to the specified
  93.         object.
  94.  
  95. OBJECT TVsendmsg1(int message,int modifier,OBJECT object)
  96.         send a parameterless message which returns a single value to the
  97.         specified object.
  98.  
  99. Windows
  100. -------
  101.  
  102. One of the strongest features of the DESQview API is its windowing
  103. capabilities.  DV-GLUE gives you the capability to create, move, resize,
  104. color, title, and close windows, among other things.
  105.  
  106. Each window has a logical cursor which need not be in the same place as the
  107. hardware cursor--after all, the hardware cursor could be in some other
  108. program's window.  There are calls to manipulate the logical cursor and move
  109. the hardware cursor to the position corresponding to the logical cursor.
  110.  
  111. OBJECT TVwin_new(OBJECT window,int rows,int cols)
  112.         create a new window which is a child of the given window and is
  113.         "rows" high and "cols" wide.  Returns the handle of the new window.
  114.  
  115. void TVwin_free(OBJECT window)
  116.         close the specified window.
  117.  
  118. void TVwin_attach(OBJECT window)
  119.         attach the specified window to its parent window, such that when one
  120.         window is moved, the other also moves.
  121.  
  122. void TVwin_detach(OBJECT window)
  123.         detach the specified window from its parent window, such that each
  124.         window moves independently of the other.
  125.  
  126. void TVwin_clear(OBJECT window)
  127.         Erase the entire window.  Does not affect the logical cursor's
  128.         position.
  129.  
  130. void TVwin_fill(OBJECT window,char c)
  131.         Fill the entire window with the specified character.
  132.  
  133. void TVwin_attr(OBJECT window,int attr)
  134.         Set the default output attribute for the given window.
  135.  
  136. void TVwin_cursor(OBJECT window,int row,int col)
  137.         Move the window's logical cursor to the specified position.
  138.  
  139. void TVwin_hcur(OBJECT window)
  140.         Move the hardware cursor to where the window's logical cursor is.
  141.  
  142. void TVwin_repchar(OBJECT window,char c,int count)
  143.         Write the character "c" to the given window "count" times.
  144.  
  145. void TVwin_repattr(OBJECT window,int attr,int count)
  146.         Change the attribute of the next "count" characters of the given
  147.         window to "attr."
  148.  
  149. void TVwin_blanks(OBJECT window,int count)
  150.         Write the specified number of blanks to the given window.
  151.  
  152. void TVwin_lsize(OBJECT window,int rows,int cols)
  153.         Change the logical size (not the displayed size) of the given window
  154.         to be "rows" high by "cols" wide.
  155.  
  156. void TVwin_origin(OBJECT window,int row,int col)
  157.         Move the upper left corner of the visible portion of the window to
  158.         be at (row,col).
  159.  
  160. void TVwin_resize(OBJECT window,int rows,int cols)
  161.         Change the size of the given window on the screen to be "rows" high by
  162.         "cols" wide.
  163.  
  164. void TVwin_move(OBJECT window,int row,int col)
  165.         Move the given window such that its upper left corner is at
  166.         (row,col).
  167.  
  168. void TVwin_minsize(OBJECT window,int rows,int columns)
  169.         Keep the user from reducing the window's size below the specified size
  170.  
  171. void TVwin_maxsize(OBJECT window,int rows,int columns)
  172.         Keep the user from increasing the window's size beyond the specified
  173.         size.
  174.  
  175. void TVwin_title(OBJECT window,char *title)
  176.         Set the window's title to the given string.
  177.  
  178. void TVwin_bottom(OBJECT window)
  179.         move the window behind all other windows belonging to the current
  180.         task.
  181.  
  182. void TVwin_top(OBJECT window)
  183.         move the window in front of all other windows belonging to the current
  184.         task.
  185.  
  186. void TVwin_topsys(OBJECT window)
  187.         move the window in front of all other windows in the system.
  188.  
  189. void TVwin_reorder(OBJECT win,unsigned first,unsigned second,...)
  190.         Put the specified window in front, with "first", "second", etc.
  191.         being put behind it.  "first", "second", etc. are the OBJSEG of
  192.         the object handle for the respective windows.
  193.  
  194. void TVwin_redraw(OBJECT window)
  195.         Update the physical screen to accurately reflect the window.
  196.  
  197. void TVredrawwin(OBJECT window)
  198.         Same as TVwin_redraw(), but uses different method to tell DESQview to
  199.         update the screen image of the window.  This method does not make the
  200.         given window active.
  201.  
  202. void TVwin_scroll(OBJECT window,int top,int left,int height,int width,int dir)
  203.         Scroll the specified region of the window's virtual screen in the
  204.         given direction.  The valid directions are
  205.                 SCRL_LEFT
  206.                 SCRL_RIGHT
  207.                 SCRL_UP
  208.                 SCRL_DOWN
  209.  
  210. int TVwin_printf(OBJECT window,char *format, ...)
  211.         Just like printf(), but writes to the specified window.  Note that
  212.         \n is not converted to \r\n, so you will have to use \r\n if you
  213.         want the remaining text to continue at the beginning of the next
  214.         line.
  215.  
  216. void TVwin_swrite(OBJECT window,char *string)
  217.         Write the string to the given window.  Note that \n is not converted
  218.         to \r\n.
  219.  
  220. void TVwin_write(OBJECT window,char *string,int len)
  221.         Write the first "len" characters of the string to the given window.
  222.  
  223. void TVwin_writeca(OBJECT window,char *chars,char *attr,int len)
  224.         Write the first "len" characters and attributes to the given window
  225.         starting at the current position of the logical cursor.
  226.  
  227. void TVwin_writea(OBJECT window,char *attr,int len)
  228.         Change the attributes of the first "len" characters from the current
  229.         cursor position to be those specified by "attr".
  230.  
  231. void TVwin_repattr(OBJECT window,int attr,int count)
  232.         change the attributes of the next "count" characters on the virtual
  233.         screen to "attr"
  234.  
  235. void TVwin_repchar(OBJECT window,int character,int count)
  236.         write "count" copies of the character to the virtual screen for the
  237.         given window.
  238.  
  239. int TVwin_read(OBJECT window,void *buffer,int maxsize)
  240.         Read the remainder of the current line in the given window, and copy
  241.         up to "maxsize" characters into the buffer.
  242.  
  243. int TVwin_nread(OBJECT window,void *buffer,int n)
  244.         Read the next "n" characters or attributes from the given window and
  245.         place them in the buffer.
  246.  
  247. void TVwin_gotoxy(OBJECT window,int x,int y)
  248.         Position windows cursor at row y and column x.
  249.  
  250. void TVwin_cursor(OBJECT window,int row,int col)
  251.         Position window's logical cursor at the given row and column.
  252.  
  253. void TVwin_color(OBJECT window,int logical_attr,int physical_attr)
  254.         Select the physical attribute for the given logical attribute.
  255.  
  256. void TVwin_frattr(OBJECT window,int attr)
  257.         set the attribute of the given window's frame.
  258.  
  259. --------------------------
  260. There are a number of switches available:
  261.  
  262. void TVwin_atread(OBJECT window,int read_attr)
  263.         If "read_attr" is nonzero, TVwin_nread() gets attributes, if
  264.         "read_attr" is zero, TVwin_nread() gets characters.
  265.  
  266. void TVwin_ctrl(OBJECT window,int ctrl)
  267.         If "ctrl" is nonzero, output to the given window will interpret
  268.         CR, LF, BS, etc.  If "ctrl" is zero, those characters will be
  269.         displayed.
  270.  
  271. void TVwin_logattr(OBJECT window,int logattr)
  272.         If "logattr" is nonzero, DESQview will translate the attributes used
  273.         for the window, i.e. the attributes become logical.  If "logattr" is
  274.         zero, then the attributes written to a window are those displayed on
  275.         the screen, i.e. physical attributes.
  276.  
  277. void TVwin_leave(OBJECT window,int leave)
  278.         If "leave" is nonzero, then writing to a window will not change the
  279.         attributes in the positions which are overwritten.  If "leave" is
  280.         zero, then characters output to the window will be given the currently
  281.         active default attribute.
  282.  
  283. void TVwin_frame(OBJECT window,int frame)
  284.         If "frame" is nonzero, then the window's frame will be displayed.
  285.         If "frame" is zero, the window will not have a frame.
  286.  
  287. void TVwin_hide(OBJECT window)
  288.         make the given window invisible
  289.  
  290. void TVwin_unhide(OBJECT window)
  291.         make the given window visible
  292.  
  293.  
  294. Query Functions
  295. ---------------
  296.  
  297. In addition to setting window characteristics, you can find out the status of
  298. most anything that you can set.
  299.  
  300. int TVqry_attr(OBJECT window)
  301.         Returns the current default character attribute for the window.
  302.  
  303. void TVqry_cursor(OBJECT window,int *row,int *column)
  304.         Returns the position of the window's logical cursor in "row" and
  305.         "column".
  306.  
  307. void TVqry_position(OBJECT window,int *row,int *column)
  308.         Returns the position of the given window in "row" and "column"
  309.  
  310. void TVqry_origin(OBJECT window,int *row,int *column)
  311.         Returns the origin of the visible portion of the window in "row" and
  312.         "column".
  313.  
  314. void TVqry_lsize(OBJECT window,int *rows,int *columns)
  315.         Returns the logical size of the window in "rows" and "columns"
  316.  
  317. void TVqry_size(OBJECT window,int *rows,int *columns)
  318.         Returns the displayed size of the window in "rows" and "columns"
  319.  
  320. void TVqry_title(OBJECT window,char *title,int size)
  321.         Returns the first "size" characters of the window's title in "title"
  322.  
  323. int TVqry_color(OBJECT win,int logical_attr)
  324.         Returns the physical attribute which the given logical attribute is
  325.         mapped to.
  326.  
  327. int TVqry_frattr(OBJECT window)
  328.         Returns the attribute of the window's frame.
  329.  
  330. int TVwin_width(OBJECT window)
  331.         Return the width of the virtual screen for the given window.
  332.  
  333. The switches which may be set can also be read:
  334.  
  335. int TVqry_atread(OBJECT window)
  336.         returns TRUE if TVwin_nread() gets attributes, FALSE if it gets
  337.         characters.
  338.  
  339. int TVqry_ctrl(OBJECT window)
  340.         returns TRUE if control characters are interpreted, FALSE if not
  341.  
  342. int TVqry_logattr(OBJECT window)
  343.         returns TRUE if logical attributes are being used, FALSE if physical
  344.         attributes are used.
  345.  
  346. int TVqry_leave(OBJECT window)
  347.         returns TRUE if writing to the window will leave the character
  348.         attributes unchanged, and FALSE if the attributes are changed to the
  349.         current default attribute.
  350.  
  351. int TVqry_frame(OBJECT window)
  352.         returns TRUE if the window has a frame, FALSE otherwise.
  353.  
  354. int TVqry_hidden(OBJECT window)
  355.         returns TRUE if the window is hidden, FALSE if it is visible.
  356.  
  357. Keyboard Objects
  358. ----------------
  359.  
  360. Keyboard objects let you direct keyboard input to a specified window, to send
  361. data that another process thinks came from the keyboard, and other things.
  362.  
  363. OBJECT TVkbd_new(void)
  364.         create a new keyboard object and return its handle.
  365.  
  366. void TVkbd_free(OBJECT kbd)
  367.         destroy keyboard object.  Do not attempt to free the default keyboard!
  368.  
  369. void TVkbd_open(OBJECT kbd, OBJECT window)
  370.         connect "kbd" to the indicated window
  371.  
  372. void TVkbd_close(OBJECT kbd)
  373.         disconnect the keyboard from its window
  374.  
  375. int TVkbd_messages(OBJECT kbd)
  376.         determine how many messages are pending for the keyboard
  377.  
  378. void TVkbd_clear(OBJECT kbd)
  379.         remove all pending messages from the keyboard
  380.  
  381. OBJECT TVmykbd(void)
  382.         return the handle of the current task's default keyboard.  For the
  383.         functions described in this section, the special handle NIL represents
  384.         the default keyboard.
  385.  
  386. OBJECT TVkbdof(OBJECT task)
  387.         return the handle for the given task's default keyboard.
  388.  
  389. int TVkbd_read(OBJECT kbd,char *buffer,int maxsize)
  390.         wait for a keyboard message on "kbd", and then fill "buffer" with up
  391.         to (maxsize-1) characters from the message.  Returns the actual size
  392.         of the message read.
  393.  
  394.         If the keyboard is in field mode, then the user can edit the input
  395.         fields at will, and the return contains the contents of all input
  396.         fields in the following format:
  397.  
  398.                 BYTE  field number
  399.                 WORD  length of field data
  400.               N BYTES contents of field
  401.  
  402.         This repeats until the field number is zero, which signals the end of
  403.         the data.
  404.  
  405. int TVkbd_status(OBJECT kbd)
  406.         return status of last message read from "kbd".  If the keyboard is in
  407.         field mode, the status will indicate how the entry was terminated.
  408.                 1  = pressed RETURN
  409.                 27 = pressed ESC
  410.  
  411. void TVkbd_write(OBJECT kbd,char *data,int size,int status)
  412.         write a message of the given size to "kbd", using the given status,
  413.         which may then be checked by the reader with TVkbd_status().
  414.  
  415. void TVkbd_setflags(OBJECT kbd,int flags)
  416.         set the keyboard behavior flags for "kbd" that correspond to the set
  417.         bits of "flags"
  418.  
  419. void TVkbd_clrflags(OBJECT kbd,int flags)
  420.         clear the keyboard behavior flags for "kbd" that correspond to the set
  421.         bits of "flags"
  422.  
  423. void TVkbd_setesc(OBJECT kbd,void far (*func)(void))
  424.         set a keyboard filtering function.  Not yet tested.
  425.  
  426. Timers
  427. ------
  428.  
  429. The timer management functions allow you to create, destroy, set, and read
  430. timer objects which can provide for delays.
  431.  
  432. OBJECT TVtimer_new(void)
  433.         create a new timer object and return its handle
  434.  
  435. OBJECT TVtimer_free(void)
  436.         destroy a timer object and return its memory to the common pool
  437.  
  438. void TVtimer_begin(OBJECT timer,DWORD length)
  439.         start a timer counting down from "length".  The timer will run for
  440.         10 * length milliseconds (though the timer's resolution is actually
  441.         only 55 milliseconds).
  442.  
  443. void TVtimer_set(OBJECT timer,int hour,int minute,int second,int hundredths)
  444.         Start a timer counting down such that it finishes at the indicated
  445.         time.
  446.  
  447. DWORD TVtimer_len(OBJECT timer)
  448.         return the amount of time left on the timer.
  449.  
  450. DWORD TVtimer_elapsed(OBJECT timer)
  451.         return the amount of time elapsed since the timer was started.
  452.  
  453. void TVtimer_start(OBJECT timer)
  454.         start the timer counting down
  455.  
  456. void TVtimer_stop(OBJECT timer)
  457.         stop the timer from counting down
  458.  
  459. void TVtimer_close(OBJECT timer)
  460.         close the timer object.  Also stops the countdown.
  461.  
  462. DWORD TVtimer_wait(OBJECT timer)
  463.         wait until the timer completes its countdown, and return the time in
  464.         1/100ths seconds since midnight at the time the counter finished.
  465.  
  466. int TVtimer_status(OBJECT timer)
  467.         find out whether the timer is running or not.
  468.  
  469. Pointers
  470. --------
  471.  
  472. OBJECT TVptr_new(void)
  473.         creates a new pointer object and returns its handle
  474.  
  475. void TVptr_free(OBJECT pointer)
  476.         destroy the given pointer object
  477.  
  478. void TVptr_open(OBJECT pointer, OBJECT window)
  479.         connect the mouse pointer to the given window, where NIL means the
  480.         current task's default window
  481.  
  482. void TVptr_close(OBJECT pointer)
  483.         disconnect the mouse pointer from its window
  484.  
  485. void TVptr_icon(OBJECT pointer,char symbol)
  486.         set the character used to represent the mouse pointer.
  487.  
  488. void TVptr_goto(OBJECT ptr,int row,int col)
  489.         move the mouse pointer to the given position relative to the window's
  490.         upper left corner
  491.  
  492. void TVptr_setflags(OBJECT pointer,WORD flags)
  493.         set pointer behavior flags.  What the flags are is not yet known.
  494.  
  495. void TVptr_clrflags(OBJECT pointer,WORD flags)
  496.         clear pointer behavior flags.  What the flags are is not yet known.
  497.  
  498. void TVptr_erase(OBJECT pointer)
  499.         discard all unread pointer messages
  500.  
  501. int TVptr_messages(OBJECT pointer)
  502.         return the number of unread pointer messages
  503.  
  504. int TVptr_read(OBJECT window,void *buffer,int maxsize)
  505.         wait for the next pointer message, and put the first "maxsize"
  506.         bytes into the buffer, returning the actual size of the message.
  507.  
  508. DWORD TVptr_status(OBJECT pointer)
  509.         return the pointer's status
  510.  
  511. void TVptr_goto(OBJECT ptr,int row,int col)
  512.         move the mouse pointer to the given position relative to the window's
  513.         upper left corner
  514.  
  515. void TVptr_setscale(OBJECT pointer,int x,int y)
  516.  
  517. void TVptr_getscale(OBJECT pointer,int *x,int *y)
  518.  
  519. void TVwin_point(OBJECT window,OBJECT pointer)
  520.         move the mouse pointer to the location of the given window's logical
  521.         cursor.
  522.  
  523. Panel Files
  524. -----------
  525.  
  526. I have no idea what the format of panel files is, so I have no way to test
  527. the panel functions.
  528.  
  529. OBJECT TVpanel_new(void)
  530.         create a new panel object and return its handle
  531.  
  532. void TVpanel_free(OBJECT panel)
  533.         destroy the panel object
  534.  
  535. void TVpanel_open(OBJECT panel,char *filename)
  536.         associate the panel object with a disk file
  537.  
  538. void TVpanel_close(OBJECT panel)
  539.         close the panel file on disk
  540.  
  541. DWORD TVpanel_status(OBJECT panel)
  542.         check whether panel object is associated with a file?
  543.  
  544. int TVpanel_size(OBJECT panel)
  545.         return the number of panels in the panel file
  546.  
  547. Object Queues
  548. -------------
  549.  
  550. Object queues let you wait for any one of multiple occurrences without
  551. creating a separate task for each, and without polling for them.
  552.  
  553. void TVobq_add(OBJECT objectq, OBJECT item)
  554.         add the specified object to the given objectq.  Using NIL for the
  555.         objectq will use the current task's objectq.
  556.  
  557. void TVobq_remove(OBJECT objectq, OBJECT item)
  558.         remove the specified object from the queue.
  559.  
  560. void TVobq_clear(OBJECT objectq)
  561.         remove ALL objects from the queue.
  562.  
  563. int TVobq_size(OBJECT objectq)
  564.         return the number of items in the specified queue.
  565.  
  566. DWORD TVobq_status(OBJECT objectq)
  567.         find out whether or not the object queue is open
  568.  
  569. void TVobq_open(OBJECT objectq)
  570.         open the given objectq.  NIL means the current task's objectq.
  571.  
  572. void TVobq_close(OBJECT objectq)
  573.         close the given objectq.  NIL means the current task's objectq.
  574.  
  575. OBJECT TVmyobq(void)
  576.         return the handle of the current task's objectq.
  577.  
  578. OBJECT TVobqof(OBJECT task)
  579.         return the handle of the given task's objectq.
  580.  
  581. OBJECT TVobq_read(OBJECT objectq)
  582.         wait for any object on the queue to have input, and return the handle
  583.         of the object which has input.
  584.  
  585. Multiple Threads of Execution
  586. -----------------------------
  587.  
  588. The task management functions allow you to create and destroy threads, and
  589. start, stop, and interrupt other threads.
  590.  
  591. OBJECT TVnew_task(OBJECT parent,char *title,int row,int col,int rows,int cols,
  592.                   char *stack,int stacksize,void (*startaddr)(int))
  593.         create a new thread as a child of "parent", whose window has title
  594.         "title" (or the title of the parent, if title == NULL).  The window
  595.         will the at (row,col) and will be "rows" lines high by "cols" columns
  596.         wide.  If stack == NULL, a stack of size "stacksize" will be malloc'd,
  597.         otherwise the given stack will be used by the new task.  The task will
  598.         begin by executing the function "startaddr", passing in the segment of
  599.         its parent task's handle.
  600.  
  601.         If "rows" is negative, then the window will have the same number of
  602.         rows as the parent window; similarly for "cols".  If both "rows"
  603.         and "cols" are zero, no new window will be created.
  604.  
  605. void TVfreetask(OBJECT task)
  606.         kill the given task.
  607.  
  608. void TVforeonly(OBJECT task,int foreonly)
  609.         Sets whether or not a task will run in the background.  If "foreonly"
  610.         if nonzero, the task will be suspended while in the background.
  611.  
  612. OBJECT TVmytask(void)
  613.         return the handle of the currently executing task
  614.  
  615. void TVinterrupt(OBJECT task,void far (*func)(void))
  616.  
  617. void TVstoptask(OBJECT task)
  618.         suspend the given task.  At least in DV 2.00, this call is ignored
  619.         unless the given task is the currently executing one.
  620.  
  621. void TVstarttask(OBJECT task)
  622.         restart the previously suspended task
  623.  
  624.  
  625. WARNING:  If you use multiple threads, you will have to ensure that library
  626. routines which are not completely reentrant have a guarded replacement which
  627. waits until any other threads have exited the function.  By default,
  628. TVAPI.H contains #define's to protect malloc(), calloc(), realloc(), and free().
  629. Other functions to watch out for are rand(), srand(), ...printf(), and
  630. ...scanf().
  631.  
  632. Applications
  633. ------------
  634.  
  635. Applications are very similar to threads, except that each application has its
  636. own code and data within a memory partition, and may contain multiple threads.
  637. When a thread is started, it inherits the code of its parent; when an
  638. application is started, it gets new code from an executable on disk.
  639.  
  640. OBJECT TVapp_new(OBJECT win,int row,int col,int rows,int cols,
  641.                  char *program, char *argv0, char *argv1, ..., NULL )
  642.         Start a new application as a child of the task owning "win".  The
  643.         new window will be at (row,col) and will be rows by cols in size.
  644.         Load "program", and start it executing with the remaining arguments as
  645.         command line.
  646.  
  647. OBJECT TVapp_start(void *pif_file, int pif_size)
  648.         Given the contents of the .PIF or .DVP file, start a new application in
  649.         a completely new memory partition.
  650.  
  651. void TVapp_free(OBJECT app)
  652.         kill the given application.
  653.  
  654. void TVapp_goback(OBJECT app)
  655.         force the given application into the background
  656.  
  657. void TVapp_gofore(OBJECT app)
  658.         force the given application into the foreground
  659.  
  660. void TVapp_suspend(OBJECT app)
  661.         hide all windows belonging to the given application and suspend it.
  662.  
  663. void TVapp_hide(OBJECT app)
  664.         hide all windows belonging to the given application.  The application
  665.         continues to run.
  666.  
  667. void TVapp_show(OBJECT app)
  668.         show the windows belonging to the given application.
  669.  
  670. Mailboxes
  671. ---------
  672.  
  673. Mailboxes provide a convenient way for different tasks to communicate.
  674. Each task gets a mailbox by default, and this is the mailbox to which
  675. asynchronous notification messages are sent (see a later section).
  676.  
  677. OBJECT TVmbx_new(void)
  678.         create a new mailbox and return its handle
  679.  
  680. void TVmbx_open(OBJECT mbx)
  681.         open a mailbox, making it available for messages.  A task's default
  682.         mailbox is opened for you.
  683. void TVmbx_close(OBJECT mbx)
  684.         close a mailbox, making it unavailable.
  685.  
  686. void TVmbx_free(OBJECT mbx)
  687.         destroy a mailbox object and return its memory to the pool of common
  688.         memory.  Do not use this function on a task's default mailbox, as
  689.         the mailbox's memory is part of the task object's memory block.
  690.  
  691. OBJECT TVmymbx(void)
  692.         return handle for current task's default mailbox.  Note that all of
  693.         the functions expecting a mailbox handle will accept NIL for the
  694.         default mailbox.
  695. OBJECT TVmbxof(OBJECT task)
  696.         return the given task's default mailbox.  This is useful for sending
  697.         mail to another task, such as a subtask you have created.
  698.  
  699. void TVmbx_name(OBJECT mbx,char *name)
  700.         give a mailbox a globally visible name.  Using the next function,
  701.         anyone can then find the mailbox knowing only the name.
  702. OBJECT TVmbx_find(char *name)
  703.         find the mailbox with the given name.  Returns NIL if there is no
  704.         mailbox with that name.
  705.  
  706. void TVmbx_clear(OBJECT mbx)
  707.         discard all pending messages from the mailbox.
  708.  
  709. int TVmbx_size(OBJECT mbx)
  710.         return the number of pending messages in the mailbox
  711.  
  712. int TVmbx_status(OBJECT mbx)
  713.         return the status of the last message read
  714.  
  715. void TVmbx_write(OBJECT mbx,int ref,int status,char *msg,int length)
  716.         send the message "msg" with the given length to the mailbox
  717.         "mbx".  The status is set to "status", and the message is passed by
  718.         reference if "ref" is nonzero, and by value (i.e. a copy is made)
  719.         if "ref" is zero.
  720.  
  721. void TVsendmail(OBJECT mbx,char *msg,int length)
  722.         send the message "msg" with the given length of the mailbox
  723.         "mbx".  The status is set to zero, and the message is passed by
  724.         value (i.e. a copy is made).
  725.  
  726. int TVreadmail(OBJECT mbx,char *buffer,int maxsize)
  727.         wait for a message to arrive in the mailbox, and then fill buffer
  728.         with up to (maxsize-1) characters of the message.  Returns the actual
  729.         size of the message read.
  730.  
  731. There are also two functions which use mailboxes to synchronize access to
  732. resources, in effect treating the mailbox as a semaphore:
  733.  
  734. void TVlock(OBJECT mbx)
  735.         request exclusive access to resource.  If another task has already
  736.         locked the mailbox, the current task will be halted until the other
  737.         task unlocks the mailbox.  It is legal to lock the mailbox multiple
  738.         times, in which case you must unlock it the same number of times that
  739.         you locked it.
  740. void TVunlock(OBJECT mbx)
  741.         release exclusive access to resource.  If this unlocking corresponds
  742.         to the last lock placed on the mailbox, then any other task waiting to
  743.         lock the mailbox may proceed.
  744.  
  745. Fields
  746. ------
  747.  
  748. Fields are used in building a data-input screen which can be filled out by the
  749. user.  After setup, a single call lets the user fill out the entire screen,
  750. after which the results can be read back.
  751.  
  752. void TVfld_header(OBJECT win,FT_HEADER header)
  753.         sets the field table header which defines how many fields there are,
  754.         the colors of the current field and selected fields, and the type of the
  755.         screen.
  756.  
  757.         The FT_HEADER structure contains the following fields:
  758.              BYTE numfields      the number of fields on the screen
  759.              BYTE type           behavior flags, see TVfld_build_header
  760.              BYTE curr_attr      attribute of current field during input
  761.              BYTE selected_attr  attribute of any selected fields
  762.              int unknown         must be zero
  763.  
  764. void TVfld_entry(OBJECT win,int field,FT_ENTRY entry)
  765.         sets up the specified field, indicating its position and type.
  766.  
  767.         The FT_ENTRY structure contains the following fields
  768.              BYTE upleftrow    \ row and column of upper left corner
  769.              BYTE upleftcol    /
  770.              BYTE lowrightrow  \ row and column of lower right corner
  771.              BYTE lowrightcol  /
  772.              BYTE type           type of the field, see TVfld_build_entry()
  773.              BYTE modifier       type modifier, see TVfld_build_entry()
  774.              BYTE status         don't quite know what this does
  775.              BYTE key2           second key of a two-key menu entry
  776.  
  777. BYTE *TVfld_build_header(int num_fields,int screen_type,
  778.                          int curr_attr,int selected_attr)
  779.         begins building a stream for a screen with "num_fields" fields, using
  780.         the given screen type, where the current field will have attribute
  781.         "curr_attr" and any selected fields will have attribute
  782.         "selected_attr".  All fields will have attribute "curr_attr" by
  783.         default, but this may be changed with TVfld_build_color() ;
  784.         Use TVfld_build_entry() and TVfld_build_color() to set the field
  785.         sizes and colors, and then use TVwin_stream(window,stream) to
  786.         send the stream to the window for which you want to define fields.
  787.         DO NOT FREE THE STREAM UNTIL AFTER YOU HAVE FINISHED A TVkbd_read()
  788.         ON THE WINDOW.
  789.  
  790.         The following behaviors may be ORed together for the screen type:
  791.                 F_NOREAD        TVkbd_read() returns no data
  792.                 F_READARRAY     read returns a packed array of chars
  793.                 F_READALL       read returns var-length records of all fields
  794.                 F_READNEW       read returns var-length records of modified
  795.                                 fields
  796.                 the above are mutually exclusive
  797.                 F_RIGHTBUTTON   right mouse button terminates entry
  798.                 F_LEFTBUTTION   left mouse button terminates entry
  799.                 F_ALLOWKBD      menu choices may be made by keystrokes
  800.  
  801. void TVfld_build_entry(BYTE *stream,int field,int upleftrow,int upleftcol,
  802.                        int lowrightrow,int lowrightcol,int type,int modifier,
  803.                        int status,int key2)
  804.         Define the given field (numbered from 1 to the number of fields) to
  805.         be the rectangle from (upleftrow,upleftcol) to
  806.         (lowrightrow,lowrightcol).  Use the specified type of field (see
  807.         below), with the given modifier and status.  "key2" should be zero
  808.         unless this is a menu entry that uses two keystrokes to select.
  809.  
  810.         The legal types of fields are
  811.                 F_NONENTRY   no entries allowed on this field
  812.                 F_MENUECHO   place where keystrokes for a two-key menu are put
  813.                 F_FILLIN     fill-in-the-blank field
  814.                 F_MENU       menu selection
  815.  
  816.         For type F_FILLIN, the legal modifiers (OR together) are:
  817.                 F_BEEP       beep when field is full
  818.                 F_NEXT       move to next field when field is full
  819.                 F_NUMBER     enter text from right to left, for numbers
  820.                 F_UPPER      force input to uppercase
  821.                 F_CLEAR      clear old field contents on first keystroke
  822.         For type F_MENU, the modifier is the first keystroke of the menu
  823.         entry, or 0 if the selection must be made with the mouse.
  824.  
  825.         If the type of the field is F_MENU, then "status" is the attribute
  826.         to use when the mouse pointer is in the field.
  827.          
  828. void TVfld_build_color(BYTE *stream,int field,int attr)
  829.         given the stream built by TVfld_build_header() and TVfld_build_entry(),
  830.         set the attribute of the given field.  Field numbers range from 1 of
  831.         the number of fields given to TVfld_build_header().
  832.  
  833. void TVfld_clear(OBJECT win,int field)
  834.         clears specified field to all blanks
  835.  
  836. void TVfld_char(OBJECT win,int field,int c)
  837.         fills the entire field with the specified character.
  838.  
  839. void TVfld_attr(OBJECT win,int field,int attr)
  840.         sets the display attribute of the specified field.
  841.  
  842. int TVfld_swrite(OBJECT win,int field,char *s)
  843.         write the characters of the string "s" to the specified field.
  844.         If the string is shorter than the field, the rest of the
  845.         field is padded with blanks.  Returns TRUE if the string could
  846.         be written, FALSE otherwise.
  847.  
  848. int TVfld_write(OBJECT win,int field,char *s)
  849.         write EXACTLY enough characters of the string "s" to the specified
  850.         field in order to fill it.  Returns TRUE if the string could be written,
  851.         FALSE otherwise.
  852.  
  853. void TVfld_cursor(OBJECT win,int field)
  854.         move the cursor to the specified field
  855.  
  856. void TVfld_scroll(OBJECT window,int field,int direction)
  857.         scroll the given field on the window one position in the specified
  858.         direction.  Legal directions are SCRL_UP, SCRL_DOWN, SCRL_LEFT,
  859.         and SCRL_RIGHT.
  860.  
  861. void TVfld_type(OBJECT window,int field,int type)
  862.         Set the field's type.  Legal types are F_NONENTRY, F_MENUECHO,
  863.         F_FILLIN, and F_MENU.
  864.  
  865. void TVfld_reset(OBJECT window)
  866.         Resets selected and modified bits on all field for the window.
  867.  
  868. void TVfld_marker(OBJECT window,char marker)
  869.         Sets the character to display at the left edge of fields which have
  870.         their "selected" bit set.
  871.  
  872. void TVfld_altmode(OBJECT keyboard,int altmode)
  873.         If "altmode" is TRUE, set the keyboard into field mode.  If "altmode"
  874.         is FALSE, set the keyboard into character mode.
  875.  
  876. unsigned TVqry_fieldsize(OBJECT window,int field)
  877.         return the size in characters of the specified field on the window.
  878.  
  879. int TVqry_field(OBJECT window,int field,int buffersize,char *buffer)
  880.         put up to "buffersize" characters of the specified field on the given
  881.         window into the buffer.  Return TRUE if the read was successful,
  882.         FALSE if not.
  883.  
  884. void TVqry_header(OBJECT window,FT_HEADER *header)
  885.         fill in "header" with the field table header, which indicates
  886.         the number of field and other information.  See TVfld_header()
  887.         above for the format of the FT_HEADER structure.
  888.  
  889. void TVqry_entry(OBJECT window,int field,FT_ENTRY *entry)
  890.         fill in "entry" with the specified field table entry.  See
  891.         TVfld_entry() above for the format of the FT_ENTRY structure.
  892.  
  893. int TVqry_type(OBJECT window,int field)
  894.         return the type byte of the specified field on the window.  This byte
  895.         is also returned by TVqry_entry() as part of the field table entry.
  896.  
  897. Asynchronous Notification
  898. -------------------------
  899.  
  900. A program running under DESQview may request to be notified when certain
  901. events occur.  When a selected event occurs, the specified handler is
  902. immediately invoked, and a message is sent to the task's default mailbox
  903. indicating which event occurred.
  904.  
  905. void TVwin_async(OBJECT win,void far (*func)(void))
  906.         Defines a notification handler for the window "win".  You may share a
  907.         handler among multiple windows, as the events which apply to a single
  908.         window identify which window was affected.
  909.  
  910. void TVwin_notify(OBJECT win,int event)
  911.         Call the notification handler set up with TVwin_async() on the
  912.         specified event.  The events are defined in TVSTREAM.H and are:
  913.                 TV_HMOVE          window was moved left or right
  914.                 TV_VMOVE          window was moved up or down
  915.                 TV_HSIZE          window's width changed
  916.                 TV_VSIZE          window's height changed
  917.                 TV_HSCROLL        window was scrolled left or right
  918.                 TV_VSCROLL        window was scrolled up or down
  919.                 TV_CLOSE          window is requested to close itself
  920.                 TV_HIDE           window was hidden
  921.                 TV_HELP           DESQview main menu "Help for Program" selected
  922.                 TV_COLORS         DESQview "Rearrange" menu "Colors" option
  923.                 TV_SWITCHEDTO     window was put in foreground
  924.                 TV_SWITCHEDAWAY   window was put in background
  925.                 TV_VIDEOMODE      "Rearrange" "Video Options" selected
  926.                 TV_SCISSORS_CUT   "Scissors" menu "Cut" option selected
  927.                 TV_SCISSORS_COPY  "Scissors" menu "Copy" option selected
  928.                 TV_SCISSORS_PASTE "Scissors" menu "Paste" option selected
  929.                 TV_MAINMENU       DESQview main menu popped up
  930.                 TV_MENU_END       DESQview main menu closed
  931.  
  932. void TVwin_cancel(OBJECT win,int event)
  933.         Turn off notification of given event for the window "win".  The events
  934.         are the same as for TVwin_notify().
  935.  
  936. void TVwin_allow(OBJECT win,int event)
  937.         Allow the specified event to occur on the window "win".  The possible
  938.         events are defined in TVSTREAM.H and are
  939.                 TV_HMOVE        horizontal movement of the window
  940.                 TV_VMOVE        vertical movement of the window
  941.                 TV_HSIZE        changing the width of the window
  942.                 TV_VSIZE        changing the height of the window
  943.                 TV_HSCROLL      scrolling the window left or right
  944.                 TV_VSCROLL      scrolling the window up or down
  945.                 TV_CLOSE        main menu "Close" option
  946.                 TV_HIDE         DESQview "Rearrange" menu "Hide" option
  947.                 TV_MARK         access to DESQview's "Mark" menu
  948.                 TV_SCISSORS     access to DESQview's "Scissors" menu
  949.                 TV_MAINMENU     allow DESQview's main menu to pop up
  950.                 TV_SWITCH       allow switching to other window
  951.                 TV_OPENMENU     access to DESQview's "Open" menu
  952.                 TV_QUIT         allow DESQview main menu "Quit" option
  953.  
  954. void TVwin_disallow(OBJECT win,int event)
  955.         disallow the given event for the window "win".  The events are the
  956.         same as for TVwin_allow().
  957.  
  958. NOTE:  if a function is not completely reentrant, you may not use that
  959. function within a notification handler unless the function cannot be called in
  960. any code from which the notification may take place.  If you are using a
  961. guarded replacement, you must still follow this restriction, as you may
  962. otherwise hang the current process.
  963.  
  964. Second-Level Interrupts
  965. -----------------------
  966.  
  967. WORD TVgetbit(void far (*handler)(void))
  968.         allocate a second-level interrupt, and set it to point to "handler"
  969.         Returns a bitmask with a single bit set, or 0 if no second-level
  970.         interrupt could be allocated.
  971.  
  972. void TVsetbit(WORD bitmask)
  973.         enqueue all second-level interrupts corresponding to set bits in the
  974.         bitmask.
  975.  
  976. void TVfreebit(WORD bitmask)
  977.         deallocate all second-level interrupts corresponding to set bits in
  978.         the bitmask.
  979.  
  980. Memory Allocation
  981. -----------------
  982.  
  983. There are a number of functions to allocate and deallocate blocks of common
  984. memory, and find out how much memory is available.
  985.  
  986. void DVcommon_mem(WORD *avail, WORD *largest, WORD *total)
  987.         sets "avail" to the total bytes of common memory available
  988.         sets "largest" to the number of bytes in the largest block of common
  989.                 memory available
  990.         sets "total" to the total number of bytes of common memory
  991.  
  992. void DVconv_mem(WORD *avail, WORD *largest, WORD *total)
  993.         sets "avail" to the total kilobytes of conventional memory available
  994.         sets "largest" to the size in K of the largest block of conv memory
  995.         sets "total" to the total size of conventional memory in K
  996.  
  997. void DVexp_mem(WORD *avail, WORD *largest, WORD *total)
  998.         same as DVconv_mem, except that it reports on expanded memory
  999.  
  1000. void far *TVgetmem(unsigned amt)
  1001.         allocate "amt" bytes of system memory and return a pointer to the
  1002.         allocated block.
  1003.  
  1004. void TVputmem(void far *block)
  1005.         return the previously allocated block of system memory to the pool
  1006.         of available memory.
  1007.  
  1008. Miscellaneous Functions
  1009. -----------------------
  1010.  
  1011. void TVpause(void)
  1012.         give up rest of timeslice to other tasks/processes
  1013.  
  1014. void TVbegincrit(void)
  1015. void TVendcrit(void)
  1016.         delimit a "critical section", during which TopView/DESQview will not
  1017.         perform task switches.
  1018.  
  1019. void TVostack(void)
  1020.         switch to task's private stack
  1021. void TVustack(void)
  1022.         switch back to user stack
  1023.  
  1024.         Use extreme caution with these two functions, as they switch the stack
  1025.         out from under your C code.  You will not be able to access local
  1026.         variables after the stack switch, and any code which assumes SS == DS
  1027.         will break.
  1028.  
  1029. void far *TVshadow(void)
  1030.         returns address of shadow buffer for the current task's main window.
  1031.         Under DESQview, it also starts shadowing, that is, automatically
  1032.         updating the display.  Under TopView, you must manually update the
  1033.         display with the next function.
  1034. void TVupdate(void far *first, WORD count)
  1035.         update the display from the shadow buffer, starting with the character
  1036.         pointed to by "first", for "count" contiguous characters
  1037.  
  1038. void far *DVshadow_start(int *rows,int *cols)
  1039.         similar to TVshadow(), but also returns size of shadow buffer in rows
  1040.         and columns.  Unlike TVshadow(), it will restart shadowing which has
  1041.         been stopped by TVupdate() or DVshadow_stop().
  1042. void DVshadow_stop(void)
  1043.         stop automatic updating of screen from shadow buffer.  In DESQview 2.0
  1044.         and higher, shadowing is also stopped by TVupdate(), but will not be
  1045.         restarted by TVshadow().
  1046.  
  1047. int DVappnum(void)
  1048.         returns the number of the current task as it appears on the "Switch
  1049.         Windows" menu.
  1050.  
  1051. WORD DVprogname(void)
  1052.         returns the offset within DESQVIEW.DVO of the current task's name.
  1053.  
  1054. void DVdbgpoke(char c)
  1055.         write the character directly to the 25th line of the screen.  After
  1056.         the character is written, the next call will place the character in
  1057.         the next position, wrapping back to the beginning of the 25th line
  1058.         if necessary.  Note that this function does not heed any windows which
  1059.         may be on the screen, nor does it work properly in graphics modes.
  1060.  
  1061. void DVjustify(int justify)
  1062.         if "justify" is nonzero, the viewport origins of windows will shift
  1063.         to keep the cursor within the visible portion of the virtual screen.
  1064.         If "justify" is zero, no such shifting will take place.
  1065.  
  1066.